# ROS 2 Humble安装指南

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档面向在 **Quectel Pi H1** 平台或同类Debian 13 (Trixie)环境中，构建自定义ROS 2 Humble运行时的开发者、系统集成商与现场交付团队，覆盖从源码同步、依赖准备、编译排障到环境变量配置与通信测试的完整路径。通过该指南，你可以：

- 获取一套针对工业/机器人场景优化的安装流程，快速建立可裁剪的ROS 2 Humble开发环境；

- 理解在纯净Debian系统上处理依赖冲突、规避Fast DDS/Connext这类商业中间件时的常见问题与解决策略；

- 构建可复现的工作空间结构，为CI、自动化部署或多设备同步提供统一模板；

- 基于附带的示例测试验证C++/Python节点互通，确保环境可直接用于后续应用开发。

# 准备工作

- 操作系统：Debian 13 (Trixie)；

- 网络：稳定的互联网连接，便于下载依赖与源码；

- 存储与时间：至少10GB可用空间，1-3小时（取决于性能与网络）；

- Python：建议Python 3.10/3.11（3.12+可能存在兼容性问题）；

- 其他建议：提前更新系统 *sudo apt-get update && sudo apt-get full-upgrade*。

# 安装步骤

- 安装基础依赖包

```bash
    sudo apt-get update && sudo apt-get full-upgrade
    sudo apt-get install -y \
    python3-flake8-blind-except \
    python3-flake8-class-newline \
    python3-flake8-deprecated \
    python3-mypy \
    python3-pip \
    python3-pytest \
    python3-pytest-cov \
    python3-pytest-mock \
    python3-pytest-repeat \
    python3-pytest-rerunfailures \
    python3-pytest-runner \
    python3-pytest-timeout \
    python3-rosdep2 \
    python3-colcon-core \
    vcstool \
    build-essential \git
```

- 创建ROS 2工作空间

```bash
mkdir -p ~/ros2_humble
cd ~/ros2_humble
```

- 获取ROS 2 Humble源代码

```bash
cd ~/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos
```

- 安装系统依赖项

```bash
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"
```

- 跳过的包说明  
    - fastcdr, rti-connext-dds-6.0.1：商业/可选依赖  
    - urdfdom_headers, python3-vcstool：可能已通过其他方式安装  
    - ignition-math6, ignition-cmake2, ignition-common3, ignition-transport8：Debian 13中不可用（Gazebo 相关，非核心功能）

- 常见错误（可以忽略）  
    - python3-sip-dev失败：GUI工具（rqt）的依赖，不影响核心功能  
    - python3-nose失败：Python 3.12+中已废弃，不影响核心功能

- 编译源码

```bash
colcon build --symlink-install
```

- 编译时可能会遇到的问题  
    - 问题1：Fast DDS相关错误  
          - 错误信息：  
      ```plaintext
      Starting >>> rmw_connextdds
      --- stderr: rmw_fastrtps_shared_cpp
      CMake Deprecation Warning at CMakeLists.txt:15 (cmake_minimum_required):
        Compatibility with CMake < 3.10 will be removed from a future version of
        CMake.

        Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
        to tell CMake that the project requires at least <min> but has been updated
        to work with policies introduced by <max> or earlier.

      CMake Error at CMakeLists.txt:47 (find_package):
        Could not find a package configuration file provided by "fastrtps"
        (requested version 2.6.2) with any of the following names:

          fastrtpsConfig.cmake
          fastrtps-config.cmake

        Add the installation prefix of "fastrtps" to CMAKE_PREFIX_PATH or set
        "fastrtps_DIR" to a directory containing one of the above files.  If
        "fastrtps" provides a separate development package or SDK, be sure it has
        been installed.

      ---
      Failed   <<< rmw_fastrtps_shared_cpp [2.60s, exited with code 1]
      ```  
          - 原因：rmw_fastrtps_shared_cpp这个包依赖Fast DDS（fastrtps）。未安装Fast DDS，所以CMake找不到fastrtpsConfig.cmake，因此报错。即使你打算使用Cyclone DDS，colcon仍会尝试构建Fast DDS相关包，除非显式跳过。  
          - 解决方法：使用Cyclone DDS时直接跳过Fast DDS系列包：  
      ```bash
        cd ~/ros2_humble
        export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
        colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release \
        --packages-skip \
        rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
        rmw_connextdds rmw_connextdds_common rmw_connextddsmicro \
        rmw_implementation
      ```  
    - 问题2：rmw_implementation构建失败  
          - 错误信息：  
      ```plaintext
      Starting >>> rmw_implementation
      [-1762327992435806464.000s] ERROR:colcon.colcon_cmake.task.cmake.build:Failed to find the following files:
      -/home/root/ros2_humble/install/rmw_fastrtps_shared_cpp/share/rmw_fastrtps_shared_cpp/package.sh
      - /home/root/ros2_humble/install/rmw_fastrtps_cpp/share/rmw_fastrtps_cpp/package.sh
      -/home/root/ros2_humble/install/rmw_fastrtps_dynamic_cpp/share/rmw_fastrtps_dynamic_cpp/package.sh
      Check that the following packages have been built:
      - rmw_fastrtps_shared_cpp
      - rmw_fastrtps_cpp
      - rmw_fastrtps_dynamic_cpp
      Failed   <<< rmw_implementation [0.40s, exited with code 1]
      ```  
          - 原因：构建系统默认会寻找Fast DDS家族的环境钩子（install下 rmw_fastrtps_* 的package.sh）。你未安装Fast DDS，因此找不到这些文件，导致rmw_implementation、rcl等失败。  
          - 解决方法：  
                  - 明确选择Cyclone DDS：`export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp`  
                  - 隐藏Fast DDS/Connext源包（避免后续扫描）：  
            ```bash
            for d in \
              src/**/rmw_fastrtps_shared_cpp \
              src/**/rmw_fastrtps_cpp \
              src/**/rmw_fastrtps_dynamic_cpp \
              src/**/rmw_connextdds \
              src/**/rmw_connextdds_common \
              src/**/rmw_connextddsmicro \; do[ -d "$d" ] && touch "$d/COLCON_IGNORE"done
            ```  
                  - 用占位package.sh临时绕过相关检查（不影响已编译产物，后续可删除）：  
            ```bash
            for p in rmw_fastrtps_shared_cpp rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp; domkdir -p /home/root/ros2_humble/install/$p/share/$pprintf '#!/bin/sh\n# placeholder for %s\n' "$p" > /home/root/ros2_humble/install/$p/share/$p/package.sh
            chmod +x /home/root/ros2_humble/install/$p/share/$p/package.sh
            done
            ```  
                  - 先构建Cyclone DDS，再构建 `rmw_implementation`、`rcl`：  
            ```bash
            colcon build --symlink-install \
            --packages-select rmw_cyclonedds_cpp \
            --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

            colcon build --symlink-install \
            --packages-select rmw_implementation \
            --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

            colcon build --symlink-install \
            --packages-select rcl \
            --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DRMW_IMPLEMENTATION=rmw_cyclonedds_cpp
            ```  
                  - 继续整编  
                  - 在解决完以上的问题后，继续进行整编：  
            ```bash
            # 继续整编（跳过Fast DDS & Connext；关闭测试，加速并减少依赖）
            colcon build --symlink-install \
            --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
            --packages-skip \
            rmw_fastrtps_shared_cpp rmw_fastrtps rmw_fastrtps_cpp rmw_fastrtps_dynamic_cpp \
            rmw_connextdds rmw_connextdds_common rmw_connextddsmicro
            ```

# 环境变量设置

编译完成后，你需要设置环境变量才能使用ROS 2：

```bash
export ros2_source=$PWDecho -e "source ${ros2_source}/ros2_humble/install/setup.bash" >> $HOME/.bashrc
source $HOME/.bashrc
```

# 使用测试

## 示例

- 打开一个终端，运行C++ talker示例：

```bash
ros2 run demo_nodes_cpp talker
```

- 打开另外一个终端，运行Python listener示例：

```bash
ros2 run demo_nodes_py listener
```

## 验证

执行完这两条命令后，您应该会看到talker端的消息：

```plaintext
ros2 run demo_nodes_cpp talker
[INFO] [1728966840.691346935] [talker]: Publishing: 'Hello World: 1'
[INFO] [1728966841.691537928] [talker]: Publishing: 'Hello World: 2'
[INFO] [1728966842.691572879] [talker]: Publishing: 'Hello World: 3'
[INFO] [1728966843.691563207] [talker]: Publishing: 'Hello World: 4'
[INFO] [1728966844.691568120] [talker]: Publishing: 'Hello World: 5'
```

和listener端的消息：

```plaintext
ros2 run demo_nodes_py listener
[INFO] [1728966840.716456921] [listener]: I heard: [Hello World: 1]
[INFO] [1728966841.698002748] [listener]: I heard: [Hello World: 2]
[INFO] [1728966842.697675740] [listener]: I heard: [Hello World: 3]
[INFO] [1728966843.697643318] [listener]: I heard: [Hello World: 4]
[INFO] [1728966844.697551980] [listener]: I heard: [Hello World: 5]
```

这说明C++和Python API均正常运行。